feat(nh): remove experimental from native histograms #2741
Conversation
|
New plan is out. Release with 3.8 (and special transition help to be removed in 3.9). Might need some updates here, but let's first wait for the plan to survive the next 24 hours or so… |
Once native histograms are released as stable, remove "experimental" word from native histograms docs. Presumably with the release of 3.8. Also fix a bunch of typos. Signed-off-by: György Krajcsovits <[email protected]> # Conflicts: # docs/specs/native_histograms.md
krajorama
force-pushed
the
krajo/nh-stable
branch
from
6c7647a to
f94acad
Compare
There was a problem hiding this comment.
In the section where we quote the proto spec, we should remove the line // Native histograms are an experimental feature without stability guarantees. (Of course, we should also do that "upstream" in the actual proto spec.)
There is still this text in the spec, which needs to be updated to the scrape_native_histograms setting:
## Scrape configuration
To enable the Prometheus server to scrape native histograms, the feature flag
`--enable-feature=native-histograms` is required. This flag also changes the
content negotiation to prefer the classic protobuf-based exposition format over
the OpenMetrics text format. (TODO: This behavior will change once native
histograms are a stable feature.)
Also, the following section about fine-tuning the content negotiation needs an update. (We can still mention the feature flag to ease transition, but we should explain mainly the status quo.)
Later, there is this:
Without the `--enable-feature=native-histograms` flag, Prometheus will
completely ignore the native histogram parts during scraping. (TODO: Update
once the feature flag has been no-op'd.) With the flag set, Prometheus will
prefer the native histogram parts over the classic histogram parts, even if
both are exposed for the same histogram. Prometheus will still scrape the
classic histogram parts for histograms with no native histogram data.
This also needs updates to the scrape_native_histograms setting.
At the top, there is a section reading
This document still contains a lot of TODOs. In most cases, they are not just
referring to incompleteness of this doc but more importantly to incomplete
implementation or open questions. For now, this is essentially a living
document that will receive updates as implementations and specifications catch
up.
We should change the wording here to make clear that the current feature set is nevertheless stable, and that the remaining TODOs are considered non-breaking.
Finally, let's update the header in practices/histograms.md that it will be rewritten at our next convenience (not "Once native histograms are closer to becoming a
stable feature" 😁 ).
| | created-timestamp-zero-ingestion | 2.50.0 | | ||
| | feature flag | Experimental | version that introduced it | | ||
| |--------------|--------------|----------------------------| | ||
| | native-histograms | no | 2.40.0 | |
There was a problem hiding this comment.
We don't want people to use the feature flag anymore. It is just there in v3.8 to ease the transition to the scrape_native_histograms config setting.
Maybe reword this section to not talk about "experimental" at all, and get rid of the table. (It feels like overkill for only two features anyway. It was probably created with the anticipation of many more features.
We explain the whole picking thing in the feature flag documentation and in the scrape config documentation anyway.
So maybe just say that native histograms and created timestamps require protobuf, that protocol selection is done in the scrape config, and that defaults are adjusted so that protobuf is preferred if native histograms or created timestamp are used.
| `--enable-feature=native-histograms`. (TODO: This is still the case with the | ||
| current release v2.55 and v3.00. Update this section with the stable release, | ||
| once it has happened.) | ||
| current release v2.xx and v3.xx. Update this section once native histograms are | ||
| enabled by default.) |
There was a problem hiding this comment.
| `--enable-feature=native-histograms`. (TODO: This is still the case with the | |
| current release v2.55 and v3.00. Update this section with the stable release, | |
| once it has happened.) | |
| current release v2.xx and v3.xx. Update this section once native histograms are | |
| enabled by default.) | |
| `--enable-feature=native-histograms`. Starting with v3.8, native histograms | |
| are supported as a stable feature. However, scraping native histograms still | |
| has to be activated explicitly via the `scrape_native_histograms` configuration | |
| setting. To ease transition from the feature flag to the configuration | |
| setting, setting the feature flag in v3.8 has the only remaining effect to | |
| set `scrape_native_histograms` to `true` by default. Starting with v3.9, | |
| the feature flag is a true no-op and explicitly setting `scrape_native_histograms` is required. |
2 participants
Once native histograms are released as stable, remove "experimental" word from native histograms docs. Presumably with the release of 3.8.
Also fix a bunch of typos.
Prerequisite: prometheus/prometheus#17232
Related to prometheus/prometheus#16572
Out of scope: rewrite https://prometheus.io/docs/practices/histograms/